// File: jmcomic-core/src/main/java/dev/jukomu/common/util/net/IResponse.java
package dev.jukomu.common.util.net;

import dev.jukomu.common.util.json.AdvancedMap;

import java.io.IOException;
import java.util.Map;

/**
 * HTTP响应的通用接口。
 */
public interface IResponse {

    /**
     * 获取HTTP状态码。
     *
     * @return HTTP状态码
     */
    int getHttpCode();

    /**
     * 判断请求是否成功（通常为200）。
     *
     * @return 如果成功返回 true
     */
    boolean isSuccess();

    /**
     * 判断请求是否不成功。
     *
     * @return 如果不成功返回 true
     */
    default boolean isNotSuccess() {
        return !isSuccess();
    }

    /**
     * 如果请求不成功则抛出AssertionError。
     *
     * @throws AssertionError 如果请求不成功
     */
    void requireSuccess() throws AssertionError;

    /**
     * 获取响应文本内容。
     *
     * @return 响应文本
     */
    String getText();

    /**
     * 获取响应的URL。
     *
     * @return URL字符串
     */
    String getUrl();

    /**
     * 获取响应头。
     *
     * @return 响应头Map
     */
    Map<String, String> getHeaders();

    /**
     * 获取响应的原始字节内容。
     *
     * @return 字节数组
     */
    byte[] getContent();

    /**
     * 获取重定向URL（如果存在Location头）。
     *
     * @return 重定向URL字符串
     */
    String getRedirectUrl();

    /**
     * 将响应解析为JSON Map。
     *
     * @return JSON Map
     * @throws IOException 如果解析失败
     */
    Map<String, Object> getJson() throws IOException;

    /**
     * 将响应解析为AdvancedMap模型。
     *
     * @return AdvancedMap模型
     * @throws IOException 如果解析失败
     */
    AdvancedMap getModel() throws IOException;

    /**
     * 获取原始响应对象。
     *
     * @param <T> 原始响应类型
     * @return 原始响应对象
     */
    <T> T getRawResponse();
}